Volume 2

Issue 3

September 2005

Case Study A case study in modular documentation Debbie Donahue Project Manager, Information Development, Unisys Debbie.Donahue@unisys.com A group of Unisys technical writers (located in Mission Viejo, CA; Roseville, MN; and Malvern, PA) recently moved to a more modular approach to creating manuals. The more modular approach to documentation was precipitated by the company strategy to use common server technology across multiple product lines. In this article, Debbie Donahue, the project manager who led the writers in the Information Development group through this change, describes their approach to and rationale for modular writing. Issues The Information Development department needed to keep pace with the Engineering development process. Unisys had started to use a modular approach to developing its products, using common server technology in multiple product lines. By doing so, Engineering was able to cut development time because they were reusing components. In the meantime, the writers couldn't keep up with the pace. The writers were also realizing that there was much overlap in the documentation they were creating, and that they could reuse common content. However, the reuse was manual, with writers e-mailing each other and using the "word of mouth" method to find content they could reuse. By employing a more managed approach to content reuse, the writers hoped to be able to keep up with the fast pace set by Engineering. What we did and why The previous documentation development process at Unisys went something like this very traditional approach: writers reviewed a combination of engineering documents, performed some hands-on testing of the products in the lab, interviewed the SME (subject matter expert), created the documents, sent the documents out for review, and so on. Writers were responsible for an entire document and saw that document through its entire life cycle. However, to keep up with Engineer's development life cycle, writers had to change their mindset about how they created documentation. The new approach to developing documentation is a modular one, mirroring the Engineering approach to developing hardware and software. We established a taxonomy that includes various roles required to create the documentation. Within the taxonomy, object owners are responsible for a set of "objects" related to a particular area. For instance, one writer might own 15 objects related to the management software. We decided to have object owners throughout the functional areas because of our continued emphasis on writers to know about and becoming experts in the content they write. It's impossible to know everything, so we thought that if writers became responsible for objects related to a particular product area, they could become experts in that product area. Within the taxonomy, we also have document leads who are responsible for taking all the objects (or content modules) and putting them together into manuals. The document leads also create the unique content required to complete the manuals. The document leads have the most product knowledge and are able to use their expertise to build documents from the various modules created by the object owners. So, object owners create the various modules required for a particular product area, and the document leads compile those modules and other unique content into manuals. Challenges The process is working extremely well, but that's not to say there are no kinks to be worked out! Probably our biggest challenge occurs when we get "squeezed." We spent a lot of time flowcharting our processes, and when there is enough time in the development cycle to follow these processes, all goes smoothly. But, when there isn't enough time, it seems we still have to scramble to get things done. When squeezed, the writers tend to go back to the old way of doing things, sometimes creating new content objects instead of reusing existing ones if they feel it takes too long to get to the existing content objects through the process. Another challenge in adopting a modular writing approach is the creation and enforcement of guidelines that describe how the content is to be written. Because content is being used in different places, it has to be written so that the modules all fit together. We have begun putting together writing guidelines to address both structure and style and are realizing that we need to be stricter in what those guidelines say and in how they are enforced. Some guidelines, especially structural ones, can be enforced through the DTD and through different mechanisms of the CMS. However, in other cases, the editing team must review documents very closely against the established standards and ensure that all pieces of the modular content adhere to the documented standards. This also means that the writers and the editing team must work most together, making sure that both writers and editors understand specifically what the guidelines mean. Another challenge is in the changing roles of writers and editors. Our modular approach works really well for some writers, but for others, the change from ownership of a complete document to ownership of a set of objects has been challenging. We did some things early on that helped writers to make the transition, including Creating a mock CMS in Word and introducing component-based authoring to an initial team of about 10 people. This initial team worked on creating components for release announcements and overview documents; team members created components and several writers would bring those components into the appropriate documents. Training our writers in structured and topic-based writing, and creating a structured writing environment with specific rules for how content must be written and structured. Having general communication events during which we talked about content reuse, content management, and structured writing, so that writers and editors were exposed to the new concepts and methodologies. Naturally, some writers are more open to doing things in a new way, but the more reluctant are also realizing the benefits of content reuse. They can see the advantages of finding content in the CMS and using it to help them meet their deadlines. Many objects are reused without alteration; only about 25 percent need some additional information specific to a particular platform. It really comes down to explaining the business reasons for creating modular documentation. The trend is for companies to do more with less, and from a business perspective, companies, including Unisys, would not be able to meet the clients' needs because they don't have the manpower to re-create content over and over again. Benefits Besides being able to create documentation more quickly, we are also starting to see some improvements in the content. Objects are rigorously edited according to style and structural guidelines, and we're seeing fewer inconsistencies in content because it is being reused. So, if the content needs to be in two manuals, it's consistent in those two manuals. When we began creating modular documentation, we focused more on the processes, which left some content as just "okay." Now, we are focusing on getting the content right and on getting good, solid guidelines put into place based on what we've learned about our content while ironing out the processes! Implementing a new method of creating manuals is always iterative. While working on the processes, we saw issues in the published content that can be addressed in the next iteration, and in the meantime, we honed our writing guidelines. Lessons learned While the modular approach is very useful and has helped us to keep up with the fast development pace, it's very important to bring writers and editors on board incrementally, showing them the benefits along the way. Training and communication are critical throughout the transition because we're changing the way that many writers and editors have worked for years. The mock CMS was very beneficial in introducing the concepts to the "early adopters" in the writing group, and through the process, other writers were able to see the benefits. It's also important that you define the scope of your project. We have such a big group of writers and such a diverse group of products. Our initial scope was to use our modular approach and the CMS for one product area, with about 30 writers. Start small and let your project expand once you're successful in one area! References [1] Rockley, Ann, Pamela Kostur and Steve Manning. 2003. Managing Enterprise Content: A Unified Content Strategy. Indianapolis, IN: New Riders. [2] Anderson, R.E. 1992. "Social impacts of computing: Codes of professional ethics." Social Science Computing Review 2, 453-469. [3] Schwartz, M., and Task Force on Bias-Free Language. 1995. Guidelines for Bias-Free Writing. Bloomington IN: Indiana University Press.